home *** CD-ROM | disk | FTP | other *** search
// VirtualDub - Video processing and capture application // System library component // Copyright (C) 1998-2004 Avery Lee, All Rights Reserved. // // Beginning with 1.6.0, the VirtualDub system library is licensed // differently than the remainder of VirtualDub. This particular file is // thus licensed as follows (the "zlib" license): // // This software is provided 'as-is', without any express or implied // warranty. In no event will the authors be held liable for any // damages arising from the use of this software. // // Permission is granted to anyone to use this software for any purpose, // including commercial applications, and to alter it and redistribute it // freely, subject to the following restrictions: // // 1. The origin of this software must not be misrepresented; you must // not claim that you wrote the original software. If you use this // software in a product, an acknowledgment in the product // documentation would be appreciated but is not required. // 2. Altered source versions must be plainly marked as such, and must // not be misrepresented as being the original software. // 3. This notice may not be removed or altered from any source // distribution. #ifndef f_VD2_SYSTEM_REFCOUNT_H #define f_VD2_SYSTEM_REFCOUNT_H #include <vd2/system/vdtypes.h> #include <vd2/system/atomic.h> /////////////////////////////////////////////////////////////////////////// // IVDRefCount /// Base interface for reference-counted objects. /// /// Reference counting is a relatively straightforward and simple method /// of garbage collection. The rules are: /// /// 1) Objects increment their reference count on an AddRef() and /// decrement it on a Release(). /// 2) Objects destroy themselves when their reference count is dropped /// to zero. /// 3) Clients create references with AddRef() and destroy them with /// Release(). /// /// One way to interact with refcounted objects is to call AddRef() /// whenever a pointer is created, and Release() when the pointer is /// nulled or changed. The vdrefptr<T> template does this automatically. /// Reference counting may be "combined" between pointers for optimization /// reasons, such that fewer reference counts are outstanding than actual /// pointers; this requires weak (non-refcounted) pointers and explicit /// refcount management. /// /// Reference counting has two issues: /// /// A) It is expensive. VirtualDub uses it somewhat sparingly. /// /// B) Reference counting cannot cope with cycles. This issue is /// avoided by arranging objects in a clearly ordered tree, such that /// no class ever holds a pointer to another object of the same class /// or to a parent in the reference hierarchy. vdrefptr<T> can /// implicitly create cycles if you are not careful. /// /// In VirtualDub, reference counting must be multithread safe, so atomic /// increment/decrement should be used. vdrefcounted<T> handles this /// automatically for the template type class. /// /// Two final implementation details: /// /// - Little or no code should be executed after the reference count /// drops to zero, preferably nothing more than the destructor implicitly /// generated by the compiler. The reason is that otherwise there is the /// potential for an object to be resurrected past its final release by /// temporarily creating a new reference on the object. /// /// - AddRef() and Release() traditionally return the reference count on /// the object after increment or decrement, but this is not required. /// For Release builds, it is only required that the value for Release() /// be zero iff the object is destroyed. (The same applies for AddRef(), /// but since the result of AddRef() is always non-zero, the return of /// AddRef() is of no use unless it is the actual count.) /// class VDINTERFACE IVDRefCount { public: virtual int AddRef()=0; virtual int Release()=0; }; /////////////////////////////////////////////////////////////////////////// // vdrefcounted<T> /// Implements thread-safe reference counting on top of a base class. /// /// vdrefcounted<T> is used to either add reference counting to a base /// class or to implement it on an interface. Use it by deriving your /// class from it. /// template<class T> class vdrefcounted : public T { public: vdrefcounted() : mRefCount(0) {} vdrefcounted(const vdrefcounted<T>& src) : mRefCount(0) {} // do not copy the refcount virtual ~vdrefcounted() {} vdrefcounted<T>& operator=(const vdrefcounted<T>&) {} // do not copy the refcount inline virtual int AddRef() { return mRefCount.inc(); } inline virtual int Release() { if (mRefCount == 1) { // We are the only reference, so there is no threading issue. Don't decrement to zero as this can cause double destruction with a temporary addref/release in destruction. delete this; return 0; } VDASSERT(mRefCount > 1); return mRefCount.dec(); } protected: VDAtomicInt mRefCount; }; /////////////////////////////////////////////////////////////////////////// // vdrefptr<T> /// Reference-counting smart pointer. /// /// Maintains a strong reference on any object that supports AddRef/Release /// semantics. This includes any interface including IVDRefCount, /// IVDRefUnknown, or the IUnknown interface in Microsoft COM. Because /// references are automatically traded as necessary, smart pointers are /// very useful for maintaining exception safety. /// template<class T> class vdrefptr { protected: T *ptr; public: typedef vdrefptr<T> self_type; typedef T element_type; /// Creates a new smart pointer and obtains a new reference on the /// specified object. explicit vdrefptr(T *p = 0) : ptr(p) { if (p) p->AddRef(); } /// Clones a smart pointer, duplicating any held reference. vdrefptr(const self_type& src) { ptr = src.ptr; if (ptr) ptr->AddRef(); } /// Destroys the smart pointer, releasing any held reference. ~vdrefptr() { if (ptr) ptr->Release(); } /// Assigns a new object to a smart pointer. Any old object is released /// and the new object is addrefed. inline self_type& operator=(T *src) { if (src) src->AddRef(); if (ptr) ptr->Release(); ptr = src; return *this; } /// Assigns a new object to a smart pointer. Any old object is released /// and the new object is addrefed. inline self_type& operator=(const vdrefptr& src) { if (src.ptr) src.ptr->AddRef(); if (ptr) ptr->Release(); ptr = src.ptr; return *this; } operator T*() const { return ptr; } T& operator*() const { return *ptr; } T *operator->() const { return ptr; } /// Removes any old reference and returns a double-pointer to the nulled /// internal pointer. This is useful for passing to IUnknown-derived /// interfaces that accept (T **) parameters, like QueryInterface(). T** operator~() { if (ptr) { ptr->Release(); ptr = NULL; } return &ptr; } /// Removes any held reference. inline void clear() { if (ptr) ptr->Release(); ptr = NULL; } /// Removes any existing reference and moves a reference from another /// smart pointer. The source pointer is cleared afterward. inline void from(vdrefptr& src) { if (ptr) ptr->Release(); ptr = src.ptr; src.ptr = NULL; } /// Removes any existing reference and accepts a reference to a new /// object without actually obtaining one. This is useful if someone /// has already addrefed an object for you. inline void set(T* src) { if (ptr) ptr->Release(); ptr = src; } /// Returns the held reference and clears the smart pointer without /// releasing the reference. This is useful for holding onto a reference /// in an exception-safe manner up until the last moment. inline T *release() { T *p = ptr; ptr = NULL; return p; } }; /////////////////////////////////////////////////////////////////////////// template<class T, class U> bool VDRefCountObjectFactory(U **pp) { T *p = new_nothrow T; if (!p) return false; *pp = static_cast<U *>(p); p->AddRef(); return true; } #endif 
